Configure CISO Assistant with OpenID Connect (OIDC)
Once you've retrieved the IdP Entity ID, the Metadata URL and the Entity ID from your provider (see the list of providers for specific details), the configuration on CISO Assistant is pretty simple.
Log in into CISO Assistant as an administrator > Extra > Settings
Navigate to SSO settings
Enable SSO
Select the OpenID Connect provider
Enter the Client ID
Enter the Client secret
Enter the Server URL
And that's it! Don't forget to click the 'Save' button
You should now be able to see the Login with SSO button
Be aware that the user needs to be created on CISO Assistant to be authenticated with SSO.
Identity providers
You can log into CISO Assistant with any identity provider (IdP), given that it supports either SAML or OpenID Connect (OIDC).
Don't find documentation on how to set up SSO with your identity provider? Feel free to reach out to us on Discord, or contribute to the docs.
Microsoft Entra ID
Configure Microsoft Entra ID as an Identity Provider for CISO Assistant
Go into your Azure portal home
Open the sidebar menu and click on Microsoft Entra ID
Click on Add button > Entreprise application
Click on Create your own application
Enter a name and then click Integrate any other application you don’t find in the gallery (Non-gallery)
Click on Single sign-on from the sidebar menu or on Set up single sign on bellowGetting Started and choose SAML
In the first box Basic SAML Configuration, specify the Entity ID, it has to be the same than SP Entity IDin CISO Assistant (see next screenshot)
Add the Reply URL: <base_url>/api/accounts/saml/0/acs/ (for example with localhost: https://localhost:8443/api/accounts/saml/0/acs/)
In the third box SAML Certificates, copy the App Federation Metadata Url as it is the Metadata URL in CISO Assistant (see next screenshot)
In the fourth box Set up <App_name>, copy the Microsoft Entra Identifier as it is the IdP Entity IDin CISO Assistant
Make sure you use the same Identifier (Entity ID) that you've set earlier and appear on block 1, on CISO Assistant SP Entity ID:
Click on Users and groups in the sidebar menu, and Add user/group to give them access to CISO Assistant with SSO. The matching key will be the email and you'll be able to grant their permissions on the applications.
You can now with the 3 parameters you've retrieved.
1. Introduction
Go to your Microsoft Azure Portal
2. Navigate to App Registrations
Adding a user in your Entra application doesn't automatically create the user on CISO Assistant
Okta
Configure Okta as an Identity Provider for CISO Assistant
Go into your Okta admin console (it should look like this: https://<your_url>.okta.com/admin/dashboard)
In the sidebar menu, click on Applications > Applications
Click now on Create App Integration
Select SAML 2.0 and click on Next
Choose an App name and click on Next
Add the Single sign-onURL: <base_url>/api/accounts/saml/0/acs/ (for example with localhost: https://localhost:8443/api/accounts/saml/0/acs/) (see screenshot below)
Add the Audience URI (SP Entity ID), it has to be the same than SP Entity ID in CISO Assistant (see screenshot below)
Choose Email as the Application username
Add Attribute Statements
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname for user's first name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname for user's last name
Click on Next and fill in the Feedback page as you wish then click on Finish
In the Settings box inside SAML 2.0:
Copy the Metadata URL and paste it into the Metadata URL field in CISO Assistant
Copy the Issuer url and paste it into theIdP Entity ID
Go to the Assignments tab
Click on Assign and choose whether you want to assign users or specific groups
Add a user in your application doesn't automatically create the user on CISO Assistant
You can now with the 3 parameters you've retrieved.
Click the App registrations section to add a new application for OIDC configuration. You can also use the search bar if you don't find it in the suggestions.
Navigate to App Registrations
3. Start New Application Registration
Start New Application Registration
4. Name your application
Name your application
5. Select Web Platform in Redirect URI options
Select Web Platform in Redirect URI options
6. Enter the callback URL of your instance
The callback URL is: <ciso_assistant_url>/api/accounts/oidc/openid_connect/login/callback/ for
for instance, for localhost: http://localhost:8000/api/accounts/oidc/openid_connect/login/callback/
Enter the callback URL of your instance
7. Complete Application Registration
Complete Application Registration
8. Copy the Application Client ID
Copy the Application Client ID
9. Past it into the Client ID field
Past it into the Client ID field
10. Open Certificates & Secrets
Open Certificates & Secrets
11. Create a New Client Secret
Create a New Client Secret
12. Add your Client Secret
Add your Client Secret
13. Copy the fresh Client Secret Value
Copy the fresh Client Secret Value
14. Past it into the Secret field
Past it into the Secret field
15. Go back to your App Overview
Go back to your App Overview
16. Inside Endpoints copy the OpenID Connect metadata URL
Inside Endpoints copy the OpenID Connect metadata URL
17. Paste it into the Server URL field
Paste it into the Server URL field
18. Save your configuration
Save your configuration
You have successfully configured OpenID Connect (OIDC) integration with EntraID.
Please note: if OIDC mode has ben configured before, you must reset the Client ID field to 0 in the OIDC tab and save before proceeding.
Failure to do so will prevent proper SAML configuration. This behavior is known and will be addressed in future releases.
Configure CISO Assistant with SAML
Once you've retrieved the IdP Entity ID, the Metadata URL and the Entity ID from your provider(see the list of providers for specific details), the configuration on CISO Assistant is pretty simple.
Log in into CISO Assistant as an administrator > Extra > Settings
Be aware that the user needs to be created on CISO Assistant to be authenticated with SSO.
SSO
Configure Single Sign-On with different SAML or OpenID Connect providers
Choose the option 1 or 2 depending of your provider and fill Metadata URLor SSO URL, SLO URL, x509 certificate retrieved from your provider
Check that the SP Entity ID is similar to the Entity/Client ID specified on your provider
And that's it! Don't forget to save changes
You should now be able to see the Login with SSO button
Allow single label domains: This allows you to authenticate through SAML on a single-label domain (e.g. https://ciso-assistant:8443). If this is left unchecked, the only host forms allowed are:
IPv4
IPv6
FQDN (e.g. https://www.example.com/)
localhost
Keycloak
Configure Keycloak as an Identity Provider for CISO Assistant
If Keycloak and CISO Assistant are both deployed locally with docker, you'll need to make sure that both containers can communicate together. You can do this with abridge network.
Go into your Keycloak admin console
Open the sidebar menu > Clients and Create client
Choose SAML client type and name it ciso-assistant or with your customSP Entity ID
Fill the Home URL with your <base_url>and Valid redirect URIs with <backend_url/*>
If you have some problems to configure these urls you can ask for help on or by emailing us
Go into Keys and disable Signing keys config
Go into Advanced and fill ACS field with <backend_url/api/accounts/saml/0/acs/> (on a cloud instance it is simply <base_url/api/accounts/saml/0/acs/>)
Go to Client scopes and click on ciso-assistant-dedicated
Add a predefined mapper and check all X500 ones
Click on X500 surname and replace SAML Attribute name with http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Click on X500 givenName and replace SAML Attribute name with http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Go into Realm settings > General, you will find the Metadata URL
You'll find inside the Metadata URL the Entity ID
Go into your Keycloak admin console
Open the sidebar menu > Clients and Create client
Choose OpenID Connect client type and give it a Client ID, then click Next
Adding a user in your application doesn't automatically create the user on CISO Assistant
You can now with the parameters you've retrieved.
Enable Client authentication, make sure Standard flow is selected, then click Next
Enter your deployment's Root URL. It is the URL of your frontend.
Set it to <frontend_url>
For cloud deployments, you must set it to <base_url>
Set the Home URL to/
Enter your Valid redirect URIs
Set it to <backend_url>/api/accounts/oidc/openid_connect/login/callback/
For cloud deployments, you must set it to <base_url>/api/accounts/oidc/openid_connect/login/callback/
Once your client is created, you can find its Client secret under the Credentials tab. You can copy it from there
Go into Realm settings > General to find the OpenID Endpoint Configuration, which you will have to paste into CISO Assistant's Server URL SSO parameter
Configure Google Workspace as an Identity Provider for CISO Assistant
Google Workspace doesn't allow callbacks to urls containing http or localhost so it can be tricky to test it locally. You should deploy CISO Assistant with a FQDN to bypass these restrictions.
Go into Google Workspace Admin console
On the sidebar menu, go to Applications > Web and mobile applications
Click on Add an application > Add a custom SAML Application
Enter ciso-assistant or the name of your choice and click on continue
You can copy the SSO URL, Entity Id and x509 certificate here but you'll be able to retreive them later
Fill ACS URL with <base_url>/api/accounts/saml/0/acs/, enter the Entity IDwhich has to be the same than SP entity Id in CISO Assistant (ciso-assistant by default) and choose Email in Name ID Format
Add two mappings for First name and Last Name, fill them with those two values: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
On application home page, you can now find the Entity ID, SSO URL and x509 certificate
Add a user in your application doesn't automatically create the user on CISO Assistant
You can now with the 3 parameters you've retrieved.
