SAML2 SSO for Ruby on Rails apps with Identity Server
Identity Server document has samples on how to configure SAML2 SSO for a Java webapp. SAML2 allows decoupling service providers from identity providers. Only requirement is ability to create/process SAML2 messages which is XML. In an identity management scenario, service provider (referred to as SP) is typically a web application. Identity provider (or IdP) is any system that provide user repository, authentication and user profile details to the service provider application.
TLDR;
If you want to skip rest of the post and go right then follow these steps,
Download and start Identity Server
Clone the modified rails project from here - https://github.com/chintana/ruby-saml-example
Create a cert keypair and update the SP cert settings in rails app
Upload public cert to Identity Server
Add an SP entry for the rails app in Identity Server (Issuer is already mentioned in app/models/account.rb
Login to Rails app - use admin/admin default credentials. You can add more users and use their accounts to login as well
Changes to the rails app
Rest of the post cover details and changes I had to do to get single sign in as well as single sign out working.
I’m using the sample skeleton rails project that’s integrated with ruby-saml. We need to configure details on connecting to Identity Server. SAML settings are in app/models/account.rb.
First up we need to change IdP settings to match what we have in Identity Server.
settings.issuer = "railsapp" settings.idp_entity_id = "localhost" settings.idp_sso_target_url = "https://localhost:9443/samlsso" settings.idp_slo_target_url = "https://localhost:9443/samlsso" settings.idp_cert = "-----BEGIN CERTIFICATE----- MIICNTCCAZ6gAwIBAg ... -----END CERTIFICATE-----"
Certificate here is default certificate that comes with Identity Server 5.1.0. I've truncated it for brevity. Then we need the following 2 entries for decrypting the encrypting SAML assertions. Certs are truncated.
settings.certificate = "-----BEGIN CERTIFICATE----- MIICfjCCAeegAwIBAgIEFFIb3D ... -----END CERTIFICATE-----" settings.private_key = "-----BEGIN PRIVATE KEY----- MIICdgIBADANBgkqhkiG9w0BAQEFAA ... -----END PRIVATE KEY-----"
When we're sending logout requests we need to include the session index with the request. So that Identity Server will logout the correct user. Rails sample doesn't send the session index by default so you'll see an exception when you do single logout saying session index cannot be null. Changes can be found here.
Then we need to make saml/logout route accessible through HTTP POST. Need to add an additional route,
post :logout
Service provider configuration in Identity Server
At the Identity Server we need to register the rails app as a service provider.
Then click on Inbound Authentication Configuration, click SAML2 Web SSO Configuration.
In the above configuration http://localhost:3000/saml/acs is the assertion consumer URL. Certificate is the certs created earlier. Also we need to configure single logout URL - http://localhost:3000/saml/logout
Tracing SAML messages
I’m using SAML Chrome extension to monitor SAML messages. First SAML call is for authentication. This is the message sent from rails app to Identity Server.
https://gist.github.com/chintana/4c1f8a090edf38a6d9ce9af7ce59a1b7
Second message is SAML response message sent from Identity Server to rails application. As you can see in the below screenshot SAML response is encrypted.
https://gist.github.com/chintana/1981b433b1e3c17983b20b4638ecc23c
Let’s do single logout from rails app. Here’s the logout request with session index.
https://gist.github.com/chintana/e5dfc587039b77ee1a2ea51b03499ff7
Then the logout response we get from Identity Server.
https://gist.github.com/chintana/0ea75ba3c326970ba85d36e66dfe6e81
With a library that supports processing SAML requests almost any web app can be integrated into Identity Server using SAML2.