Single Sign-On (SSO) is a boon for everyone using your cloud. In a previous post, we’ve covered used GSuite for SSO in OnApp. This time, I’d like to show how to configure your OnApp cloud for single sign-on with SAML and Active Directory.
It’s a bit of a long post – but once you’re done, your cloud customers or users will thank you…
SSO benefits for enterprises & service providers
If you’re a cloud service provider, password fatigue is one of the most common causes of helpdesk tickets: people have to remember so many different passwords, that inevitably they forget some – and so your helpdesk is flooded with password reset requests. SSO takes away a lot of that pain. In addition, most cloud providers today want to offer multi-factor authentication, and SSO is becoming part of security compliances such as HIPAA and SOX.
If you’re an enterprise running OnApp as your private cloud, then you’re likely to be using external identity stores already (such as Windows Active Directory) for user management, authentication, and provisioning. Therefore, leveraging the AD (Active Directory) setup while implementing security controls for your organization, saves a lot of time in the onboarding process for users in your cloud.
How SSO, ADFS, AD and 2FA work in OnApp
Active Directory Federation Service (ADFS) integrates with Active Directory, allowing it to be used as an identity provider. ADFS can interact with Web Services and SAML 2.0 compliant federation services, as a federation partner, and provide single sign on capabilities with 2 factor authentication (2FA).
OnApp can be configured to use ADFS for claims-based authentication. In addition to providing SSO and 2FA, this can also be used as a provisioning mechanism to automatically create and add users inside OnApp, from Active Directory, without any additional actions.
So, if you have multiple service offerings that use Active Directory – and you also use OnApp for your cloud – then you can bring all your user management under a singular entity such as Active Directory.
How to add OnApp to your AD/ADFS setup
It might look like a convoluted process, but adding OnApp to your AD/ADFS setup is actually quite easy for a seasoned Windows Administrator. In the rest of this post I’ll take you through the steps required. Reading further assumes that you have knowledge of Active Directory and ADFS – ideally you are already using ADFS as an Idp for other services that you offer. Ok, let’s get started.
Step 1: inside your Active Directory…
First, we need to create some custom attributes in Active Directory. This is because the default attributes do not contain attributes specific to OnApp, such as the attributes we will use to assign Roles or Groups in OnApp, to the users, which syncs across from Active Directory. After that, we will map these attributes inside OnApp – thus defining a set of common claims which will be returned from AD to OnApp via our ADFS server.
By default Active Directory does not have the functionality present to create custom attributes, but it can be activated with a simple command. There are plenty of web resources which show how to enable and create custom attributes in Active Directory – for example, this schema editing guide from Microsoft.
The attributes you need to create are as follows:
|Attribute||AD Common Name*||Type**||Purpose|
|OnApp Sync||OnAppSYNCENABLED||Boolean||The key which enables the synchronization of the attributes below during every log-in to OnApp; third party system users who are not yet registered in OnApp will not be created without this key. Syntax is Boolean which means this can have a True or False value.|
|User email||OnAppUserEmail||String||The user’s email address|
|User name||OnAppUserName||String||The user’s log-in name. Cannot be changed or synchronized after creating: if this key is missing the email address will be used as a login name for the user.|
|Roles||OnApp_Roles||String||The key of the role attribute, which will create/sync the user’s role in OnApp.|
|User group||OnApp_UserGroup||String||The group attribute to assign the user to a particular group.|
|Time zone||OnApp_TimeZone||String||The key of the time zone to which the user will be associated.|
*AD Common Name is the name assigned to this attribute in Active Directory. I have created some samples above.
** Type is the Syntax for the key.
If you already have attributes for User Email and Username, then you can substitute the common name for what you have configured in your environment.
The screenshot below is a sample “User Properties” from Active Directory of Domain controller: you can see I have defined the attributes (beginning with “OnApp”) and assigned them values. The OnApp attributes you see below are the Common Names from Table above. You can call these attributes whatever you like, but make sure that in Step 2 we use the same Common Name that we have in AD for Attribute Mapping in OnApp.
Next, we will configure OnApp to use these attributes and automate user creation and authenticate users. As we are using ADFS as our identity provider, all information about the attributes is held outside of OnApp and in your Active Directory.
Step 2: forward, unto OnApp!
Navigate to your OnApp Control Panel and access Settings -> Authentication. Click on the “Saml Id Providers” button and add a New SAML Id Provider:
Here I need to add a few settings:
- Enabled – move the slider to the right to enable this identity provider at the login screen.
- Name – enter the name of the identity provider. If you use multiple identity providers then make sure that this is something unique to identify this Idp.
- Icon – select the icon file which will be displayed at the login screen – this will help identify the provider.
- Issuer – the name of the service provider. By default, it’s the address of your OnApp Control Panel e.g. https://onapp.internet.lab/.
- Idp sso target url – the URL of your ADFS server to which the authentication request should be sent. For example, this would be like https://adfs.mydomain.com/adfs/ls
- Idp cert fingerprint – the SHA1 fingerprint of you ADFS certificate, you can get that by opening your ADFS certificate on your machine and navigating to details tab:
- Idp cert – the identity provider’s certificate in PEM format; or your ADFS signing certificate in PEM format.
- Encrypted assertion – move the slider to the right if assertion is encrypted and you want to decrypt it. For this, add a certificate in the Private key field which appears when slider is enabled (we are not going to use this in our example)
- Nameid format – specify a format of name identifier according to SAML specification. We will leave this at the default, which is “emailAddress”.
Setup Attribute mappings to match the Active Directory Common Name that you defined in the table above in step 1. So if the user group key you want to use is called “OnAppGroups” then type that inside the box. This is case sensitive – case sensitivity is one of the most common issues when you are trying to troubleshoot!
After above information is populated, go ahead and click Save. The next page you see should have all information filled, so verify that it is correct. You should also see a URL at the bottom of the page:
Click on the URL and save the resulting metadata.xml file somewhere safe, because we need it for the next step – which is, to let our ADFS server know that it has a new trusted party.
Step 3: educating the ADFS Server…
Now we are going to manage our ADFS service, so access your ADFS server’s management console and click Add Relying Party Trust…
Follow the wizard, and when you get to “Select Data Source” choose “import data about relying party from a file”. Here we will add the metadata.xml file that we got from OnApp:
After saving the relying party, open its properties, go to the Advanced tab, and change its hash algorithm to SHA-1:
Now we are going to Edit the Claim rule to map Active Directory Attributes we created in Active Directory and OnApp, to our ADFS claims.
Rule1: Send LDAP Attributes as Claims (the outgoing claim type should match what you defined in OnApp):
- E-Mail-Addresses -> E-Mail Address
- onappSyncEnabled -> onappSyncEnabled
- onappRole -> onappRole…
- …map all custom attributes to claims.
Rule2: Transform an Incoming Claim:
- E-Mail Address -> Name ID, format: Email
Ok! Now, if a user points their browser to OnApp, they should something like the login screen below, where we will have the additional sign-in options that we created:
If you click on your provider you will be re-directed to a screen looking something like this:
Once you provide your Active Directory credentials, assuming you are a new user, you will be redirected back to OnApp’s first welcome screen, and you will find that your Group and Role is set to what we defined earlier in our Active Directory Attributes:
You should now be able to provision users in Active Directory, and have them automatically created inside OnApp on their first successful login attempt – with all the benefits of SSO.
OnApp documentation for this feature is available at https://docs.onapp.com/display/55AG/SAML+Authentication. If you need any further help, drop a line to OnApp support. Thanks!