Skip to main content

Setup

warning

This feature is experimental.

Some of the current limitations are:

  • No update support for OIDC profiles or policies.
  • We only support client-secret based client authentication.
  • Claims can only be filtered with logical AND.

Prerequisites​

  • Unified Access is enabled for your organization. If in doubt or you want to have it activated please contact support.
  • An OpenID Connect Identity Provider for representing users.
  • An OAuth Client (confidential recommended but not required), including:
    • allowed redirect localhost (you may specific a specific port). No other URLs are required.
    • email claim in the ID Token.
  • You are at least an 'OrgAdmin' in your organization.
  • spirlctl in a version of at least v0.18.0.
  • (In case of self-hosted SPIRL servers) at least a version of v0.16.0 deployed in trust domains where unified-access is or needs to be enabled. Other trust domains can run an older version.

Concepts​

Unified Access OpenID Connect Profile​

Unified Access OpenID Connect (OIDC) Profiles are an organization level entity that makes SPIRL aware of your IDP and the client SPIRL uses to connect to it. You can use an OIDC profile for all your trust domains or create a dedicated one for each trust domain if the need arises.

Unified Access Policy​

A Unified Access Policy describes how the OIDC Profile should translate to SPIFFE concepts. It allows you to restrict access based on certain claims and includes ways to control how the SPIFFE ID should be constructed and how long issued credentials should be valid.

A policy is used to enable Unified Access in a trust domain.

Administration steps​

Verify status​

At any stage you can use spirlctl to check the Unified Access status of a trust domain in your organization.

spirlctl exp trust-domain unified-access status \
    --trust-domain my-trust-domain

Create Unified Access OpenID Connect Profile​

Use spirlctl to create a OIDC profile

# Add a unified access OIDC profile with client authentication using client secret
spirlctl exp trust-domain unified-access oidc add my-oidc-config \
    --issuer-url https://example.com \
    --client-id my-client-id \
    --client-secret my-client-secret

--client-secret is optional but recommended.

Other means of client authentication such as key-based are not supported yet.

Create Unified Access Policy​

Use spirlctl to create a policy

# Add a developer identity issuance policy using defaults
spirlctl exp trust-domain unified-access policy add my-policy \
    --oidc-profile my-oidc-config

You can specify custom credential lifetimes or restrict access by certain claims:

[...]
  --svid-ttl 1h \
  --filter group=admin \
  --filter group!=guest

All filters are logically combined with AND. No filter gives access to any user that can login with the specific client id of the OIDC config.

Activate unified access on a trust domain​

Use spirlctl to enable unified access in your trust domain my-trust-domain. You can repeat this step for every trust domain you need it to be enabled (and same policy applies).

spirlctl exp trust-domain unified-access enable \
    --trust-domain my-trust-domain \
    --policy my-policy

(Optional) Setup federation​

Unified Access works great with federation. You can create a dedicated trust domain for your unified-access needs and federate it with trust-domains of your workloads. No additional steps apart from the federation setup is needed particularly for developer access. The trust bundle of federated trust domains is synced automatically.

Keep in mind to federate the trust domains bi-directionally if you want to mutually validate peer SVIDs (e.g. via mTLS).

Generate user configuration​

Using unified access with spirlctl requires some configuration to indicate what policies is active and where the SPIRL server is located. An administrator can generate configuration and make changes. The configuration can be distributed to developers.

Use spirlctl to generate config.

spirlctl exp trust-domain unified-access generate-config \
    --trust-domain my-trust-domain \
    --print

The resulting JSON file can be changed to accommodate self-hosted SPIRL servers.

{
  "unified_access": {
    "my-trust-domain": {
      "agent_endpoint_address": "td-abcdf12345.agent.spirl.com:443",
      "policy_name": "my-policy"
    },
  }
}
  • agent_endpoint_address: Describes the endpoint of the agent API that is used for unified access purposes too. This can either point to your trust domain specific endpoint at spirl.com or a self-hosted SPIRL server. This endpoint needs to be accessible by developers.
  • policy_name: The name of the policy to use.

Developer steps​

Store configuration file​

Use the configuration file given to you by your administrator and store it at $HOME/.spirl/unified-access/config.json.

The following commands are then available to you: