SAML SSO with OKTA using Ruby

A minimal Ruby implementation of SAML Single Sign-On (SSO) with Okta as the Identity Provider (IdP).

Prerequisites

• Ruby 3.0+
• Bundler
• An Okta developer account
• A configured SAML application in Okta

Local Setup

1. Clone the repository.

git clone https://github.com/your-repo/saml-sso-ruby.git
cd saml-sso-ruby

2. Install Dependencies with make puma-dev.

3. Load & configure Environment Variables touch .env && cat .env.example > .env

4. Create IDP on okta developer dashboard

   • Download the Okta certificate from your Okta SAML application settings.
   • Save it as cert/okta_cert.pem.

5. If you want SAML assertion to be encrypted then follow this step:

   • Run the below command to generate a private key and certificate.
   • Upload the generated certificate.crt to your Okta SAML application settings for assertion encryption.
   • and set IS_ASSERTION_ENCRYPTED to true

openssl req -x509 -nodes -sha256 -days 3650 -newkey rsa:2048 -keyout cert/private.key -out cert/certificate.crt

6. Start the server using puma-dev (i.e, run make run)

---

Other Notes

Setting Up SAML Authentication with Okta

1. Log in to Okta Developer Account
   • Go to Okta Developer Login and sign in with google kamandlabalashekhar@gmail.com with 2fa via okta verify (otp code)
2. Create Users and Groups
   • Create the following users:
     • kamandlabalashekhar+1@gmail.com
     • kamandlabalashekhar+2@gmail.com
     • kamandlabalashekhar+3@gmail.com
     • kamandlabalashekhar+4@gmail.com
   • Create the following groups for role-based access control:
     • ruby_saml_auth_group_0 → Includes all users.
     • ruby_saml_auth_group_1 → Includes users with an odd user ID.
     • ruby_saml_auth_group_2 → Includes users with an even user ID.
   • Note: Grouping users allows you to control access levels and enforce different authorization policies in your application.
3. Create a SAML 2.0 Application
   • Navigate to Applications > Create App Integration and select SAML 2.0.
   • Configure the following settings:
     • App Name: ruby_saml_auth
     • Single Sign-On (SSO) URL: https://ruby-saml-auth.test/acs
       • Note: This is the Assertion Consumer Service (ACS) endpoint where Okta will send SAML responses after authentication.
     • Audience URI (SP Entity ID): ruby-saml-auth
       • Note: This uniquely identifies your application within the organization. It must match the value expected by your application.
     • Attribute Statements (optional):
       • firstName, lastName, email, etc.
       • Note: These attributes provide user-specific data to the application.
     • Group Attribute Statements (optional):
       • Enable all groups using regex .*.
       • Note: This allows the application to receive group information for authorization decisions.
4. Configure Advanced Settings
   • Enable Assertion Encryption and select AES256-CBC.
     • Note: Encrypting assertions ensures secure transmission of sensitive authentication data.
   • Generate and Upload Certificates:
     • Generate a public key certificate locally (see README of project).
     • Upload it as the Encryption Certificate in Okta.
     • Upload another as the Signature Certificate for signing SAML responses.
     • Note: These certificates are essential for verifying the integrity and confidentiality of SAML assertions.
   • Enable Single Logout (SLO) and configure the SLO Endpoint:
     • https://ruby-saml-auth.test/logout?slo=true
     • Note: SLO ensures that users are logged out from Okta and the application simultaneously.
   • Set SP Issuer: ruby-saml-auth
     • Note: This must match the Audience URI to establish trust between the application and Okta.
5. Assign Users and Groups to the Application
   • Assign the previously created users and groups to the ruby_saml_auth application.
   • Note: Only assigned users can authenticate via SAML for this application.
6. Retrieve SAML Metadata and Configure Environment Variables
   • Download the SAML metadata from Okta.
   • Extract and set the following values in your application's environment variables:
     • IDP_SSO_TARGET_URL → The SSO login URL from Okta metadata.
     • IDP_ENTITY_ID → The Okta Entity ID from metadata.
     • IDP_LOGOUT_URL → The Single Logout (SLO) URL from metadata.
   • Note: These values allow your application to correctly communicate with Okta during authentication and logout.
7. Enable Multi-Factor Authentication (MFA)(optional)
   • Go to Security > Multifactor in the Okta Admin Console, enable Email Authentication, and activate it.
   • Then, in Applications > [Your App] > Sign On, add an MFA rule under Sign-On Policy to prompt users for verification (e.g., every sign-in, weekly, or monthly).