OCI IAM SAML SP Demo

Implementation Guide

OCI IAM SAML SP Demo User Guide

Use this guide when pulling the application onto a new compute instance, preparing the runtime, configuring OCI IAM, and testing SAML login/logout.

What This App Does

This application is a Node.js Express SAML 2.0 Service Provider for OCI IAM Identity Domains. It exposes public setup pages, SAML metadata, an Assertion Consumer Service endpoint, a protected user page, and a configuration center.

Public pages
/, /config, /metadata, /metadata/download, /userguide
Protected pages
/user and /profile
SAML endpoints
/login, /saml/acs, /saml/logout

New Compute Checklist

  1. Provision an OCI Compute instance with a public IP or a DNS name.
  2. Open inbound traffic for ports 80, 443, and 22 in the VCN security list or NSG.
  3. Point the domain DNS A record to the compute public IP if using a domain.
  4. Install Node.js 20 or later, npm, Nginx, PM2, and OpenSSL.
  5. Copy or clone this project to the compute instance.
  6. Install dependencies with npm install if node_modules is not already present.
  7. Create or confirm the SP certificate files in certs/sp.key and certs/sp.crt.
  8. Configure .env, /config, Nginx, and OCI IAM.

Install Runtime Packages

On Oracle Linux, install the runtime components before starting the application.

sudo dnf install -y nodejs npm nginx openssl
sudo npm install -g pm2

If the project was pulled without dependencies, install them from the project directory.

cd /home/opc/oci-iam-saml-sp-demo
npm install

Generate a development SP certificate only if certs/sp.key and certs/sp.crt do not already exist.

chmod +x scripts/generate-sp-cert.sh
./scripts/generate-sp-cert.sh

Configure The Application

Start with .env.example, then update .env for the new compute environment.

SettingPurpose
PORTLocal Express port, usually 3000.
BASE_URLExternal HTTPS base URL, such as https://mingyuet.online.
SESSION_SECRETRandom value used to sign Express sessions.
SP_PRIVATE_KEY_PATHPath to the SP private key.
SP_CERT_PATHPath to the SP certificate published in metadata.
CONFIG_ADMIN_TOKENAdmin token required when saving settings on /config.
ENABLE_LOCAL_USER_ALLOWLISTWhen true, only enabled users in the local user file can enter the SP after OCI login.

After the app is running, open /config and update the public IP/domain. Derived endpoints such as ACS, Entity ID, metadata, login, and logout URLs are generated from the domain.

Set Up OCI IAM

  1. Go to OCI Console, then open Identity & Security, Domains, and the target identity domain.
  2. Create a SAML application or open the existing SAML application.
  3. Use the values from this app's /config page under OCI IAM SAML Application Values.
  4. Set the Assertion Consumer URL to https://mingyuet.online/saml/acs.
  5. Set the Entity ID to https://mingyuet.online/metadata.
  6. Use NameID format emailAddress and map NameID to the user's primary email.
  7. If using SLO, set Single Logout URL and Logout Response URL to https://mingyuet.online/saml/logout.
  8. Download or copy the OCI IAM IdP metadata XML.
  9. Return to /config, import the IdP metadata XML, or manually enter the OCI IAM SSO URL, IdP signing certificate, metadata entity ID, and OCI IAM logout URL.
  10. Restart the app after IdP metadata, domain, signing, or signature validation settings change.

The OCI IAM logout URL is the IdP SingleLogoutService endpoint from OCI metadata. It is not a normal browser page; the app sends a SAML LogoutRequest there.

Local Test Users

OCI IAM authenticates the user. The local user file is an optional SP-side test gate for lab validation.

User file
./data/test-users.json
Enable allowlist
Set ENABLE_LOCAL_USER_ALLOWLIST=true and restart the app.
Add or delete users
Use /config with the admin token from CONFIG_ADMIN_TOKEN.

If a valid OCI IAM user is rejected, they may still have an OCI IAM browser SSO session. Sign out from OCI IAM, use a private window, or add the user to the allowlist before trying again.

Run The Application

For local validation, start the app directly.

npm start

For compute-hosted usage, run with PM2.

pm2 start src/server.js --name oci-iam-saml-sp-demo
pm2 save

Restart after configuration changes that affect SAML startup settings.

pm2 restart oci-iam-saml-sp-demo --update-env

How To Use The App

  1. Open https://mingyuet.online/ to confirm the app is reachable.
  2. Open https://mingyuet.online/metadata or download metadata from /metadata/download.
  3. Use /config to verify endpoints, update domain/IP, import IdP metadata, and maintain local test users.
  4. Open https://mingyuet.online/user to test protected access.
  5. After successful OCI IAM login, the app redirects to /user and displays the SAML profile and attributes.
  6. Use Logout on /user. If SLO is configured, the app initiates OCI IAM logout; otherwise it clears only the local SP session.

Troubleshooting

SymptomLikely CauseAction
Browser cannot reach siteDNS, firewall, security list, Nginx, or app process issueCheck DNS A record, OCI ingress rules, Nginx status, PM2 status, and port 3000.
OCI says certificate is missingOCI expects signed requests but the SP certificate is not uploadedImport the SP metadata into OCI or disable request signing for initial testing.
Invalid document signatureResponse/assertion signature expectation mismatch or wrong IdP certImport the correct OCI IAM IdP metadata and verify signature flags.
Login rejected after valid OCI authenticationLocal allowlist is enabled and user is not in the fileAdd the user on /config, disable allowlist, or test with an allowed user.
Logout returns to logged-in stateOCI IAM SSO session still exists or SLO is not configuredConfigure OCI IAM SLO metadata, restart the app, or sign out from OCI IAM manually.

Home Configuration Download SP Metadata