This guide describes how to configure an identity provider (IdP) for user authentication and authorization in a silo.
Overview
Oxide supports two different modes of integration with third-party identity provider systems:
SAML Authentication + Just-in-time (JIT) User Provisioning
SAML Authentication + System for Cross-Domain Identity Management (SCIM) User Provisioning
SAML authentication is used in both cases to enable single sign-on. Any identity provider that supports SAML 2.0 can be used. The difference between JIT and SCIM is in how and when users and groups are imported into Oxide.
The integration mode is configured during silo creation and is immutable. We recommend that you try out the IdP integration setup in test silos and walk through the silo management process before creating user silos and putting irreplaceable workloads in them.
SAML Authentication + JIT User Provisioning
Users who are successfully authenticated via SAML SSO are automatically created in Oxide. Their associated groups are auto-created if the Group Attribute Name is specified in the identity provider configuration and a matching name is present in the Group Attribute Statement section of the SAML response.
Requirements
The following attributes are required when configuring an identity provider:
| attribute | value | ||||||
|---|---|---|---|---|---|---|---|
name | A short name of the silo’s IdP SAML configuration (the name will be used in the login URL path, see the example under ACS URL). For ease of tracking, this can be set to the same value as the application or service provider identifier in the IdP, but it is not required. | ||||||
description | A brief description of the SAML configuration in the identity provider. | ||||||
idp_metadata_source | Base64 encoded XML of identity provider SAML descriptor; the source can be specified as XML data or a URL for retrieving the metadata. If the URL is used, the rack service must have anonymous access to the endpoint.
| ||||||
idp_entity_id | IdP SAML issuer ID or client root URL. Examples: | ||||||
sp_client_id | The IdP ID that uniquely identifies the Oxide client; it may be labeled as service provider, application, audience, and so on. | ||||||
acs_url | The Oxide Console login endpoint registered with the identity provider for responses and assertions. It follows the naming convention
https://$siloName.sys.$oxideDomainName/login/$siloName/saml/$providerName.
For example, if the silo name is
| ||||||
slo_url | Single logout endpoint, may be set to the same value as ACS URL (i.e., taking users back to the Oxide Console login page). | ||||||
technical_contact_email | Email address of identity provider support contact (Note: Oxide rack does not generate email notifications at this time). | ||||||
signing_keypair | (Optional) Used by the client for signing the login request, in the form of base64-encoded DER files.
| ||||||
group_attribute_name | The custom attribute in the SAML access token response that represents the user’s group memberships. The information will be used to create user groups and assign the user to them (required for JIT user provisioning). |
Known Limitations and Behavior
Fleet or silo administrators can only assign Oxide roles to groups or users that are already in the system and may not be able to pre-configure access for all the relevant IdP groups. For this reason, JIT provisioning is more suitable for deployments that have simpler tenancy setup where there is a small set of pre-defined user groups and the fleet admin has memberships in all the groups.
JIT provisioning only creates or modifies users and groups but does not delete them when they are removed from the IdP application. To terminate any existing access an offboarded user may still have, silo administrators will need to invoke the logout command to expire the user’s active access tokens. Any further interaction with the system will require them to log in again. The combination of disabling a user in the IdP and calling the logout endpoint for that user effectively eliminates their ability to interact with the Oxide system.
Configuration Examples
The following guides provide detailed instructions on how to create the identity provider for the Oxide silo. The steps may vary slightly depending on the specific configuration and features you want to use, but the general process is similar across different identity providers.
Each of the guides above will walk you through the process of adding a new identity provider to the Oxide silo, including the required fields and values to enter based on the identity provider you are using. The guides will also cover how to validate the configuration and test the login process.
If you prefer to use Oxide API for the setup, see also the API example here.
SAML Authentication + SCIM User Provisioning
The SCIM 2.0 protocol defines a standardized schema and API for managing users and groups in a centralized IdP and synchronizing them to a service provider. Silos created in Oxide on version 17 or above can be configured to use the SAML+SCIM option. Users and groups can be imported into Oxide once the IdP is integrated with Oxide, allowing the fleet administrator to pre-configure silo access policies.
API Endpoints
Oxide’s SCIM 2.0 integration provides the following endpoints for user and group CRUD operations:
| Resource | Endpoint | Operations | Description |
|---|---|---|---|
User | /scim/v2/Users | GET, POST, PUT, PATCH, DELETE | Retrieve, add, and modify users. |
Group | /scim/v2/Groups | GET, POST, PUT, PATCH, DELETE | Retrieve, add, and modify groups. |
API requests are authenticated via the bearer token specified in the HTTP header. Here is an example:
-H "Authorization: Bearer oxide-scim-ab50712591ad9960ebe527e4eafe9f78b87b4fe7"
Bearer tokens can be managed by silo administrators or by fleet administrators on behalf of all silos.
Deactivating Users
Users can be deactivated by setting the active property to false. When this
happens, all of the user’s sessions and tokens are deleted, cutting them off
from API and console access. Other configuration for that user, such as SSH keys
and group memberships, is not affected and will come back into effect if they
are reactivated.
Known Limitations
Query parameters such as
startIndexandcountare unsupported at this time.filteronly supports exact match byuserNameon users anddisplayNameon groups.Group display names must be unique within their silo.
The use of nested groups is not supported at this time. Set up your Oxide app access with direct user group memberships such that users are imported when groups are pushed to Oxide.
Disabled and even deleted users can still SSH into instances they created if they still have their SSH keys — this is determined only by the public keys that are set in the VM.
SCIM v2.0 implementations vary across different identity providers. Schema and API variations may cause certain user/group CRUD workflows to behave in unexpected ways.