Customers that use Microsoft Active Directory can connect their directory with their cioplenu server to authenticate users and manage access to the application. This avoids duplication of user data and provides better security and access control since no passwords need to be transmitted to the cioplenu server and user data can be managed from one central place. This single sign-on feature can be used in parallel with normal password authentication.
The main requirement for an integration with a customer's Active Directory is that it's available as an:
If you are using Microsoft Office 365, that's most likely already the case. For existing on-premise directories Microsoft offers Azure AD Connect Sync to connect the local directory to the Azure cloud securely.
The cioplenu server will then be registered as an app on the Azure Active Directory. It will use Microsoft's Oauth2 endpoints to authenticate users when they log into the cioplenu application as well as to fetch basic information like their name.
If the cioplenu server is located behind a firewall on the customers premises an integration with Azure Active directory is still possible if cioplenu can access the Microsoft identity platform online. Authentication with Kerberos, ADFS or LDAP on an on-premise Active Directory is currently not supported.
Step-by-step guide for the integration
Before getting started please make sure that the following things are given:
- All relevant users for cioplenu must be stored in Azure Active Directory or synced from an on-premise directory to the cloud
- All users must have access to the cioplenu server and the Microsoft login portal on their devices
- The cioplenu Server must be able to reach the Azure Active Directory Oauth2 endpoints (https://login.microsoftonline.com/)
1) Register an application with Azure Active Directory
Login to the Azure Portal and make sure you have the appropriate permissions to register applications with your Azure Active Directory. Navigate to "Azure Active Directory" then to "App registrations" and click on "New registration". Enter a name for the application and set the supported account types. You most likely only want to allow single tenant access. Click "Register" to get redirected to the Overview page for the new application. Official Microsoft documentation for registering an application: https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app
2) Redirect URLs
Navigate to the "Authentication section" of the newly registered application. Enter the following redirect URLs for your company server with the type "Web".
Replace domain name with the one for your cioplenu application. For example if you reach your cioplenu instance under
mycompany. Allow Access tokens and ID tokens in the "Implicit Grant" section of the Authentication Section. Save your changes.
3) Add Token configuration
To use first and last name as well as email address from Azure you need to configure additional optional claims for the ID tokens. You can do this in the "Token configuration" section. The needed claims are
given_name. This is necessary if you want to use the full functionality of cioplenu for example when it comes to automatic email notifications for Tasks.
You might also need to add the
profile API permissions for the app for this to work. Azure will show a warning if it's not yet configured.
4) Activate the Azure Login in cioplenu
Copy the Application ID and the Directory ID from the overview page of the registered Azure Active Directory Application. Login to your cioplenu Editor with a user account that has the permission to change settings. Navigate to Settings → Azure Login in the Editor. Enter the Application ID and Directory ID you copied from Azure here and activate the Azure Login with the switch.
If desired select a default role for users who log in with Azure for the first time.
5) Login with Azure
If you now log out of the Editor you should see a new "Azure Login" button. If it's not yet visible reload the page. At the first login you will have to confirm that cioplenu is allowed to access your account information. You can consent on behalf of your organization if you want to. Users which have logged in with Azure are marked in a special "Azure" Column in the "User" section of the settings. If you don't see this column you need to activate it in the table configuration in the bottom left corner.
The cioplenu integration with the Azure Active Directory uses the Oauth2 Implicit grant flow. That means both the cioplenu server and clients need to access the Microsoft identity platform.
Cioplenu's applications redirect the user to a Login Page under https://login.microsoftonline.com. After the user has entered his credentials or after Microsoft has verified his Active Directory Sign-In on his machine it redirects the user back to the cioplenu application providing it an Access Token and an ID token. The URL it redirects to need to be configured in the Azure Portal but don't need to be accessible for Microsoft. Only the users Browser needs to be able to access both the Microsoft page and the cioplenu application.
The cioplenu application then passes the id token to the cioplenu API using an HTTP `Authorization` Header. The API service then decodes and verifies the token against a signature from Microsoft. That signature is acquired via requests to https://login.microsoftonline.com and cached on the server for 24 hours as recommended by Microsoft. If the cioplenu server is hosted On-Premise it needs to have access to that URL to be able to acquire the signature.
The tokens from the initial login will then expire after a while and the cioplenu application will preform a silent refresh. For that no user interaction is required but the user's device still needs access to https://login.microsoftonline.com and be able to redirect back to the cioplenu server in the background.
When a user logs out of the cioplenu application he is offered to log out of his Microsoft account as well. If he does not want to do that, he can just close the tab at that point. If the user logs out of his Microsoft account while authenticated in cioplenu the next token refresh will fail and he will be redirected to the cioplenu login page as well.
Further links and resources
- How to restrict access to cioplenu for a certain group of users in Azure AD: After integrating with Azure active directory every user in your directory can initially authenticate with cioplenu. In the default settings they will only have limited permissions, but everybody will be able to access the basic interface. To limit the login itself to a certain group follow this documentation.
- Office 365 documentation for Active Directory Synchronization: Introduction to Microsoft's hybrid identity model for on-premises Active Directories from the perspective of Office 365. The same identity models are available for cioplenu.
- Accessing Azure Active Directory with an Office 365 subscription: If you are not using Azure yet but only Office 365 this is how you access your Azure Active Directory.