Skip to main content

Enterprise SSO Configuration

Initial configuration​

This section describes how to configure Defakto to use Enterprise SSO.

Defakto supports OAuth+OIDC authentication using the Authorization Code Flow. To configure it, follow these steps:

Add Defakto URLs to your IDP​

Add the Defakto Application in your IDP provider settings using the following Redirect URLs:

https://auth.api.defakto.security/auth/web/finish
https://auth.api.spirl.com/auth/cli/finish

The web console and the spirlctl CLI currently authenticate through different domains. The web console uses auth.api.defakto.security, while the CLI still uses auth.api.spirl.com. Allow-list both Redirect URLs so that browser and CLI logins both succeed. The CLI Redirect URL will move to the defakto.security domain in a future release.

note

If you are migrating from the legacy console at https://app.spirl.com, see Migrating to the new console domain below.

Provide us with your IDP information​

After configuring your IDP, contact us to provide the following information:

  • Issuer URL
  • Client ID
  • Client Secret (if required)

Defakto uses the Issuer URL as the base to retrieve the OIDC Discovery document (i.e. /.well-known/openid-configuration), which contains the JWKS URL that Defakto uses to verify ID tokens issued by the enterprise IDP. Both the Discovery Document URL and the JWKS URL must be accessible from Defakto.

CLI Login Flow with Enterprise SSO​

When logging in with the spirlctl CLI using Enterprise SSO, provide the --org flag with the organization name. The organization name is provided to you by the Defakto support team.

spirlctl login --org <organization-name>

After running this command, spirlctl will open the browser and redirect you to the IDP login page. After successful login, you will be redirected back to the CLI.

Here is what is happening during the login flow with Enterprise SSO:

  1. The CLI opens a gRPC stream to the Defakto Control Plane and sends a login request
  2. Defakto identifies which social login or organization to log in with and starts an OAuth2 authorization code grant session
  3. Defakto sends back a URL in the format https://auth.api.spirl.com/auth/cli/start?session_id=<session_id>
  4. The CLI opens the Web Browser with the session URL, or the user can copy and paste the URL to the browser on a different device
  5. The Web Browser navigates to the session URL and Defakto redirects to the IDP login page
  6. The user logs in with the IDP
  7. The IDP responds with a redirect back to the URL that points to Defakto https://auth.api.spirl.com/auth/cli/finish
  8. The Web Browser performs the redirect, passing the authorization code to Defakto
  9. Defakto extracts all required parameters from the received URL. It performs a token exchange with the IDP, parses and verifies the ID token, uses the claims to authenticate the user, and generates a Defakto token.
  10. Defakto returns the token to spirlctl, completing the login session and closing the gRPC stream.

Web UI Login Flow with Enterprise SSO​

When logging in with the Defakto Web UI using Enterprise SSO, you should provide the organization name. The organization name is provided to you by the Defakto support team.

  1. The user opens the browser and loads https://console.defakto.security
  2. The user chooses Sign in with enterprise identity, enters an organization name, and clicks the Sign In button
  3. Web Browser sends a request to https://auth.api.defakto.security/auth/web/start
  4. Defakto identifies which organization to log in the user with and starts an OAuth2 authorization code grant session
  5. Defakto sends back an authorization URL pointing to the IDP
  6. The Web Browser opens the authorization URL
  7. The user logs in with the Enterprise IDP
  8. After authentication, the Enterprise IDP returns a redirect URL that points to Defakto https://auth.api.defakto.security/auth/web/finish
  9. Web Browser navigates to the redirect URL that creates a user session
  10. Defakto sends the user session back to the Web Browser

Migrating to the new console domain​

The Defakto web console is available at https://console.defakto.security. The legacy console at https://app.spirl.com continues to work, but new sign-ins should use the new domain.

The console experience is determined by the URL you visit. https://console.defakto.security uses the auth.api.defakto.security authentication and api.defakto.security API endpoints, while https://app.spirl.com uses the auth.api.spirl.com and api.spirl.com endpoints. The originating domain also determines the invitation URLs generated when you invite a user to your organization.

To start using the new console with Enterprise SSO, add the new web redirect URL to your IDP's allowlist:

https://auth.api.defakto.security/auth/web/finish

If you also use the spirlctl CLI, keep the spirl.com CLI redirect URL allowlisted:

https://auth.api.spirl.com/auth/cli/finish

After your IDP configuration is updated, sign in at https://console.defakto.security.