🔐 f5-oidc-sso-simulator

The f5-oidc-sso-simulator provides a OIDC/SSO simulation environment to test user authentication, App/API authorization, and ID/access token claims' retrieval via your IdPs for the following persona and scenarios.

Persona	Scenario
Product Manager, Solution Architect	New IdP Support: I want to test new IdPs to ensure my app's implementation supports it before selling the app.
Solution Engineer, Customer Support	SSO Troubleshooting: I want to test customers' IdP configuration without using my app as one of troubleshooting steps when getting authN errors.
Enterprise Customer	Token Claim Extract: I want to extract and check ID/access token claims with securely protecting PII without using public sites when configuring an IdP.
Software Engineer, Quality Engineer	OIDC Test Env: I want to quickly configure and run SSO test environments when testing my apps.

🏠 Getting Started

1. Prerequisites

• IdP Setup: Create an app in your IdP. Use the following URIs if you want to run this tool locally.

  Category	URI Example
  Redirect URI	https://host.docker.internal:443/_codexch
  Post Logout Redirect URI	https://host.docker.internal:443/_logout

• Clone this repo

  git clone https://github.com/f5devcentral/f5-oidc-sso-simulator.git

• Docker: Install and Run Docker
• Host: Edit hosts file when testing your app locally:

  $ sudo vi /etc/hosts
  127.0.0.1 host.docker.internal

• Nginx Plus Free Trial: Download Nginx Plus license files, and copy nginx-repo.crt and nginx-repo.key to ./myconfig/certs/.

2. Configure a Simulator

• Create a file (e.g., ./myconfig/settings-xxx.env) that contains environment variables by referencing ./myconfig/settings-bundle.env.

• Edit environment variables.

  IDP_CLIENT_ID=${edit-your-idp-app-client-id}
  IDP_CLIENT_SECRET=${edit-your-IDP_CLIENT_SECRET}
  IDP_WELL_KNOWN_ENDPOINTS=${edit-your-idp-well-known-endpoint}
  IDP_PKCE_ENABLE=true <- set to false if you want to use credentials
  IDP_DNS_RESOLVER=${edit-your-DNS-resolver-IP-address}

3. Run the Simulator as Docker Containers

• Start Docker containers:

  make start

• Check Docker containers' status:

  make watch

  

4. Run a Web Browser and Test OIDC/SSO

• Run a Web Browser with https://host.docker.internal and click Sign in/out button:

  Landing Page	IdP Sign in	User Info after Sign-in

• Check ID/access token claims and test API authorization

  ID Token Claims	Access Token Claims	Proxied API Authorization

  Note:

  • Ensure ID token contains OIDC standard claim names of given_name, family_name, email for F5 Distributed Cloud(XC) Customers before configuring F5 XC SSO.
  • Authentication error will be occured with XC if your IdP doesn't return ID token.
  • User Account Information form will be shown in XC if the ID token doesn't contain standard claims.

📚 References

• NGINX OIDC Core and App Examples for multiple Identity Providers
• Amazon Cognito Setup & Nginx Config Example
• Auth0 Setup & Nginx Config Example
• Azure Entera ID (a.k.a. AD) Setup & Nginx Config Example
• Keycloak Setup & Nginx Config Example
• Okta Setup & Nginx Config Example
• OneLogin Setup & Nginx Config Example
• Ping Identity Setup & Nginx Config Example
• Google SSO Setup & F5 Distributed Cloud Example
• Custom SSO Setup & & F5 Distributed Cloud Example