Skip to main content

Enterprise SSO 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 the Defakto Application in your IDP provider settings with the following information: Redirect URIs:

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

After configuring your IDP, contact Defakto 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 URI that Defakto uses to verify ID tokens issued by the enterprise IDP. Both the Discovery Document URL and the JWKS URI contained within 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 and will be logged in.

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

  1. spirlctl opens 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 a login session OAuth2 authorization code grant session
  3. Defakto sends back URL in the format https://auth.api.spirl.com/auth/cli/start?session_id=<session_id>
  4. spirlctl opens the Web Browser to session URL, or 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 does the redirect, passing the authorization code to Defakto
  9. Defakto extracts all required parameters from the received URL. It does 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.

Enterprise SSO Login Flow

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://app.spirl.com
  2. The user chose Sign in with enterprise identity then inputs an organization name and clicks the Sign In button
  3. Web Browser sends a request to https://auth.api.spirl.com/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. 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.spirl.com/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

Enterprise SSO Web UI Login Flow