OneLogin SAML Integration¶
This article explains how to integrate the One Login Web portal with AuthControl Sentry.
The following external OneLogin article maybe a useful reference:
OneLogin requires http://www.w3.org/2001/10/xml-exc-c14n# canonicalisation. Check that your version of OneLogin supports this.
Create SAML Keys on CMI¶
Keys are used within SAML to create a trust relationship between Sentry (acting as an IDP) and a SAML-compliant service provider. It is important that you create your own keys for this integration and keep the private key secure.
From the CMI Main Menu select the Appliance Option, then select Sentry Menu option.
You will see the keys that are currently being used by Sentry (if any).
Select Option 1 to Generate New Keys
Give the key a name eg SentryProductionKey Select the key type, RSA or DSA (RSA is recommended for wider compatibility).
Some integrations require keys of a specific type so refer to the appropriate integration guides.
You then need to enter the information required to generate the key. These parameters are:
- Country Name e.g. US. This should be the standard 2-letter ISO country code.
- State or Province e.g. Washington.
- Locality: e.g. Seattle.
- Organisation: Your Company or Organisation Name.
- Organisation Unit: Relevant unit, e.g. Information Technology.
- Common Name: The full server hostname, e.g. sentry.domain.com.
- Email Address: contact email address for the certificate.
Once you have entered all the details the new keys and certificate will be created.
You will be asked if you want to start using the new key immediately. If you say NO you can select the key at a later date.
Changing the key being used will impact any existing SAML-based integrations. The existing service providers will need to be updated with the new keys.
Selecting a Key¶
Select the Select New Key option will list all the keys that have been created on the appliance. You can select the key you wish to use.
You need to restart tomcat for the changes to take effect.
Configure Check Password with Repository on the Swivel Core¶
In order to check the user’s Active Directory password, ensure that the “local” Agent defined under Server -> Agents has got the Check Password with repository checkbox enabled. When an authentication occurs in AuthControl Sentry, the Active Directory password will then be passed to Active Directory for verification.
If you just want to test Swivel Core authentication without checking Active Directory passwords, you can leave this setting off for the time being. When prompted for a password during login on the AuthControl Sentry Login screen, simply leave the password field blank.
In order to set-up your Onelogin domain to use Auth Control Sentry as its Identity Provider you first need to log into the OneLogin Admin Console.
You then need to go to Settings-> Security-> Trusted IdPs. This will take you to a page where you can add an IdP by clicking the NEW TRUST button.
Create a new Trust called Swivel (or something of your own choosing) and complete the following settings:
- “Issuer”: This is the issuer of the SAML assertion. This is set within settings.properties so this entry needs to match that set within settings.properties.
- “IdP Login Url”: This will be the external URL of your Sentry login page. For example if the public hostname of your Sentry server is sentry.domain.com this value would be https://sentry.domain.com:8443/sentry/saml20endpoint
This can also be an IP address and need not be https, but for production hostname and https are recommended.
- “Email Domains”: If your OneLogin account covers multiple domains you can list the domains here that you want to use this IdP. If you only have one domain this field can be left blank.
- “Sign Users into ..”: You can configure this IdP to log users into their OneLogin account only or into this account and any applications that have been added to this account.
- “Trusted IdP Certificate”: This is the certificate that Sentry will use to sign the SAML assertion. You can get this information by logging onto to the Sentry admin console and using the view certificates option or view metadata option. You need to cut and past the certificate information, inlcuding the begin and end certificae header and footer by ensuring that no whitespace is added.
- “User Attribute”: This is an optional field to be used if, for example, users are logging in with attributes other than their email address.
You need to add the OneLogin application to the Sentry admin console. If you have the option to add “OneLogin” as an application type use this option. If not then select the SwivelServiceProvider option.
You need to specify:
- “Name:” OneLogin
- “Image: ” OneLogin.png (Selected by default)
- “Points:” The number of points required to access this service
- “Portal URL:” https://yourdomain.onelogin.com
- “Endpoint URL” This is the URL to which the Sentry server will redirect the user with their SAML assertion after authentication. This will be in the format of yourdomain.onelogin.com/sessions/saml. In this case domain is the domain you have registered with OneLogin.
- “Entity ID” This will be in the format of https://yourdomain.onelogin.com
- “Federated Id” email
Visit your AuthControl Sentry Page with your public DNS entry of your Swivel AuthControl Sentry server, e.g. https://mycompanysentrydomain/sentry/startPage
On the Start Page you will be able to see a new OneLogin Icon on which you can click and proceed with authentication (as you would by going straight to the OneLogin page).
You should be redirected to the Sentry Login Page.
After you enter the username we are prompted with another authentication method (in this example we use turing)
After you enter your authentication credentials you successfully will see the OneLogin account that you tried to access.
There are various logging components available for this particular integration which can aid in diagnosis at different points during authentication.
- The Swivel Core has a Log Viewer menu item which can reveal information concerning user status e.g. is the user locked, has a session been started for the image request;
- The Swivel AuthControl Sentry has a View Log menu item which provides details about the SAML assertion and response received from OneLogin
It is crucial when troubleshooting, to pinpoint where the authentication is failing. For example, you may find that the Swivel Core logs show a successful authentication (which would indicate that the user has entered their Password and OTC correctly), but the AuthControl Sentry logging shows that there is a problem with the SAML assertion.
Two common issues which can be diagnosed with the validator are:
Certificate or decryption issues;
- Can AuthControl Sentry find the Certificate locally, is it the correct one?
- Has the correct Metadata been uploaded to the OneLogin?
- Does the Repository -> Attribute name being used actually map to a Repository attribute? Has a User Sync occurred in the Swivel Core since modifying this?
Most common issues are likely to be related to the SAML response and whether the OneLogin portal will accept it.
To see the SAML response that Sentry is generating you can use a Firefox Plug-in called SAML Tracer: https://addons.mozilla.org/en-GB/firefox/addon/saml-tracer/
There are also some on-line tools you can use to validate the SAML assertion: https://www.samltool.com/